---
title: WRITER Tools
---

This guide provides an overview for getting started with WRITER [tools](/oss/langchain/tools). For detailed documentation of all WRITER features and configurations, head to the [WRITER docs](https://dev.writer.com/home).

## Overview

### Integration details

| Class                                                                                                      | Package          | Local | Serializable | JS support |                                        Downloads                                         |                                        Version                                         |
|:-----------------------------------------------------------------------------------------------------------|:-----------------| :---: | :---: |:----------:|:------------------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------:|
| [GraphTool](https://github.com/writer/langchain-writer/blob/main/langchain_writer/tools.py#L9) | [langchain-writer](https://pypi.org/project/langchain-writer/) |      ❌       |                                       ❌                                       | ❌ | ![PyPI - Downloads](https://img.shields.io/pypi/dm/langchain-writer?style=flat-square&label=%20) | ![PyPI - Version](https://img.shields.io/pypi/v/langchain-writer?style=flat-square&label=%20) |
| [TranslationTool](https://github.com/writer/langchain-writer/blob/main/langchain_writer/tools.py) | [langchain-writer](https://pypi.org/project/langchain-writer/) |      ❌       |                                       ❌                                       | ❌ | ![PyPI - Downloads](https://img.shields.io/pypi/dm/langchain-writer?style=flat-square&label=%20) | ![PyPI - Version](https://img.shields.io/pypi/v/langchain-writer?style=flat-square&label=%20) |
| [WebSearchTool](https://github.com/writer/langchain-writer/blob/main/langchain_writer/tools.py) | [langchain-writer](https://pypi.org/project/langchain-writer/) |      ❌       |                                       ❌                                       | ❌ | ![PyPI - Downloads](https://img.shields.io/pypi/dm/langchain-writer?style=flat-square&label=%20) | ![PyPI - Version](https://img.shields.io/pypi/v/langchain-writer?style=flat-square&label=%20) |

### Features

`ChatWriter` supports several tool types: `function`, `graph`, `translation`, and `web_search`.

> **Important limitation**: You can only use one WRITER tool (translation, graph, web_search, llm, image, vision) at a time. While you can't combine multiple WRITER tools, you can use one WRITER tool alongside multiple custom function tools.

#### Function

Functions are the most common type of tool, which allows the LLM to call external APIs, fetch data from databases, and generally perform any external action you want to do. Visit WRITER's [tool calling docs](https://dev.writer.com/home/tool-calling) for additional information.

#### Graph

The `Graph` tool uses WRITER's Knowledge Graph, which is a graph-based retrieval-augmented generation (RAG) system. When using this tool, developers provide a graph ID that references their specific Knowledge Graph. The model then uses this graph to find relevant information and generate accurate answers to questions in the prompt. This allows the model to access and utilize custom knowledge bases during conversations. For more details, see WRITER's [Knowledge Graph API docs](https://dev.writer.com/home/knowledge-graph).

#### Translation

The translation tool allows you to translate text during a conversation with a Palmyra model. While Palmyra X models can perform translation tasks, they are not optimized for these tasks and may not perform well without correct prompting. See WRITER's [translation API docs](https://dev.writer.com/home/translation-tool#translate-text-in-a-chat) for more information.

#### Web Search

The web search tool allows you to search the web for current information during a conversation with a Palmyra model. While Palmyra models have extensive knowledge, they may not have access to the most current information or real-time data. The web search tool enables your AI assistant to find up-to-date information, news, and facts from the web. See WRITER's [web search API docs](https://dev.writer.com/home/web-search-tool#web-search-in-a-chat) for more information.

## Setup

Sign up for [WRITER AI Studio](https://app.writer.com/aistudio/signup?utm_campaign=devrel) to generate an API key (you can follow this [Quickstart](https://dev.writer.com/home/quickstart)). Then, set the `WRITER_API_KEY` environment variable:

```python
import getpass
import os

if not os.getenv("WRITER_API_KEY"):
    os.environ["WRITER_API_KEY"] = getpass.getpass("Enter your WRITER API key: ")
```

## Usage

You can bind graph or function tools to `ChatWriter`.

### Graph Tools

To bind graph tools, first create and initialize a `GraphTool` instance with the `graph_ids` you want to use as sources:

```python
from langchain_writer.chat_models import ChatWriter
from langchain_writer.tools import GraphTool

chat = ChatWriter()

graph_id = getpass.getpass("Enter WRITER Knowledge Graph ID: ")
graph_tool = GraphTool(graph_ids=[graph_id])
```

### Translation Tools

The translation tool allows you to translate text during a conversation with a Palmyra model. While Palmyra X models can perform translation tasks, they are not optimized for these tasks and may not perform well without correct prompting.

To use the translation tool, import and initialize the built-in `TranslationTool`:

```python
from langchain_writer.tools import TranslationTool

# Initialize the translation tool
translation_tool = TranslationTool()
```

### Web Search Tools

The web search tool allows you to search the web for current information during a conversation with a Palmyra model. While Palmyra models have extensive knowledge, they may not have access to the most current information or real-time data. The web search tool enables your AI assistant to find up-to-date information, news, and facts from the web.

To use the web search tool, import and initialize the built-in `WebSearchTool`:

```python
from langchain_writer.tools import WebSearchTool

# Initialize the web search tool with optional configuration
web_search_tool = WebSearchTool(
    include_domains=["wikipedia.org", "github.com", "techcrunch.com"],
    exclude_domains=["quora.com"]
)
```

## Instantiation

```python
from typing import Optional

from langchain_core.tools import tool
from pydantic import BaseModel, Field


@tool
def get_supercopa_trophies_count(club_name: str) -> Optional[int]:
    """Returns information about supercopa trophies count.

    Args:
        club_name: Club you want to investigate info of supercopa trophies about

    Returns:
        Number of supercopa trophies or None if there is no info about requested club
    """

    if club_name == "Barcelona":
        return 15
    elif club_name == "Real Madrid":
        return 13
    elif club_name == "Atletico Madrid":
        return 2
    else:
        return None


class GetWeather(BaseModel):
    """Get the current weather in a given location"""

    location: str = Field(..., description="The city and state, e.g. San Francisco, CA")


get_product_info = {
    "type": "function",
    "function": {
        "name": "get_product_info",
        "description": "Get information about a product by its id",
        "parameters": {
            "type": "object",
            "properties": {
                "product_id": {
                    "type": "number",
                    "description": "The unique identifier of the product to retrieve information for",
                }
            },
            "required": ["product_id"],
        },
    },
}
```

### Binding tools

**Important note**: WRITER only allows a single WRITER tool (translation, graph, web_search, llm, image, vision) to be bound at a time. You cannot bind multiple WRITER tools simultaneously. However, you can bind multiple custom function tools along with one WRITER tool.

```python
# ✅ Correct: One WRITER tool + multiple function tools
llm_with_tools = chat.bind_tools(
    [graph_tool, get_supercopa_trophies_count, GetWeather, get_product_info]
)

# ✅ Correct: Different WRITER tool + function tools
llm_with_tools = chat.bind_tools(
    [translation_tool, get_supercopa_trophies_count, GetWeather]
)

# ❌ Incorrect: Multiple WRITER tools (will cause BadRequestError)
llm_with_tools = chat.bind_tools(
    [graph_tool, translation_tool, web_search_tool]  # This will fail
)
```

If you need to use different WRITER tools, you have several options:

**Option 1: Rebind tools for each conversation**:

```python
# Use graph tool for one conversation
llm_with_tools = chat.bind_tools([graph_tool, get_supercopa_trophies_count])
response1 = llm_with_tools.invoke([HumanMessage("Use the knowledge graph to answer...")])

# Switch to translation tool for another conversation
llm_with_tools = chat.bind_tools([translation_tool, get_supercopa_trophies_count])
response2 = llm_with_tools.invoke([HumanMessage("Translate this text...")])
```

**Option 2: Use separate ChatWriter instances**:

```python
# Create separate ChatWriter instances for different tools
chat_with_graph = ChatWriter()
llm_with_graph_tool = chat_with_graph.bind_tools([graph_tool])

chat_with_translation = ChatWriter()
llm_with_translation_tool = chat_with_translation.bind_tools([translation_tool])
```

## Invocation

The model will automatically choose the tool during invocation with all modes (streaming/non-streaming, sync/async).

```python
from langchain_core.messages import HumanMessage

# Example with graph tool and function tools
llm_with_tools = chat.bind_tools([graph_tool, get_supercopa_trophies_count])
messages = [
    HumanMessage(
        "Use knowledge graph tool to compose this answer. Tell me what the first line of documents stored in your KG. Also I want to know: how many SuperCopa trophies have Barcelona won?"
    )
]

response = llm_with_tools.invoke(messages)
messages.append(response)

# Example with translation tool
llm_with_translation = chat.bind_tools([translation_tool])
translation_messages = [
    HumanMessage("Translate 'Hello, world!' to Spanish")
]

translation_response = llm_with_translation.invoke(translation_messages)
print(translation_response.content)  # Output: "¡Hola, mundo!"

# Example with web search tool
llm_with_search = chat.bind_tools([web_search_tool])
search_messages = [
    HumanMessage("What are the latest developments in AI technology? Please search the web for current information.")
]

search_response = llm_with_search.invoke(search_messages)
print(search_response.content)  # Output: Current AI developments based on web search
```

In the case of function tools, you will receive an assistant message with the tool call request.

```python
print(response.tool_calls)
```

Then you can manually handle tool call request, send to model and receive final response:

```python
for tool_call in response.tool_calls:
    selected_tool = {
        "get_supercopa_trophies_count": get_supercopa_trophies_count,
    }[tool_call["name"].lower()]
    tool_msg = selected_tool.invoke(tool_call)
    messages.append(tool_msg)

response = llm_with_tools.invoke(messages)
print(response.content)
```

With a `GraphTool`, the model will call it remotely and return usage info in the `additional_kwargs` under the `graph_data` key:

```python
print(response.additional_kwargs["graph_data"])
```

The `content` attribute contains the final response:

```python
print(response.content)
```

## Chaining

The WRITER Graph tool works differently from other tools; when used, the WRITER server automatically handles calling the Knowledge Graph and generating responses using RAG. Because of this automated server-side handling, you cannot invoke the `GraphTool` independently or use it as part of a LangChain chain. You must use the `GraphTool` directly with a `ChatWriter` instance as shown in the examples above.

## API reference

For detailed documentation of all `GraphTool` features and configurations, head to the [API reference](https://python.langchain.com/api_reference/writer/tools/langchain_writer.tools.GraphTool.html#langchain_writer.tools.GraphTool).
